home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / recio202.zip / usage.txt < prev    next >
Text File  |  1994-05-05  |  23KB  |  665 lines
  1.     Title: STANDARD USAGE OF C LANGUAGE RECIO LIBRARY
  2. Copyright: (C) 1994 William Pierpoint
  3.   Version: 2.02
  4.      Date: May 5, 1994
  5.  
  6.  
  7.  
  8. 1.0 INTRODUCTION
  9.  
  10. The implementation descibed by this standard usage is a superset of the
  11. recio specification.  Enhancements are noted in the text.
  12.  
  13.  
  14. 1.1 Mnemonics
  15.  
  16. The recio functions have been given a consistent mnemonic naming
  17. convention.  All recio functions are in lower case and start with
  18. the letter r.  Function names are analogous to <stdio.h> functions.
  19. Mnemonics are as follows:
  20.  
  21. Single letter (field functions)               Multi-letter
  22. ----------------------------------------      -----------------
  23. b - base (prefix)                             beg - beginning
  24. c - column (prefix), character (suffix)       ch  - character
  25. d - double (suffix)                           col - column         
  26. f - float (suffix)                            cxt - context        
  27. i - integer (suffix)                          eof - end of file
  28. l - long (suffix)                             err - error          
  29. n - number                                    fld - field buffer
  30. r - record pointer (first letter)             fn  - function
  31. s - string pointer (suffix)                   no  - number         
  32. u - unsigned (suffix)                           rec - record buffer  
  33.                           siz - size of buffer
  34.                           str - string
  35.                           txt - text
  36. 1.2 Order
  37.  
  38. The order in which the prefix mnemonics appear indicates the order in which
  39. the arguments appear in the function.  The suffix mnemonics of the input 
  40. functions tell you what the function returns.  The suffix mnemonics of the 
  41. output functions indicate the last argument and tell you what the function 
  42. outputs.  All output functions return an integer with a zero value if the 
  43. function executed successfully.
  44.  
  45. For example, the input function rbgetui():
  46.  
  47.     arguments:  r - record pointer
  48.                 b - base (radix) of input
  49.       returns: ui - unsigned integer
  50.  
  51. The output function rbputui():
  52.  
  53.     arguments:  r - record pointer
  54.                 b - base (radix) of input
  55.                ui - unsigned integer is output
  56.  
  57. Note: c is used in the prefix of a function's name only once even if there are 
  58.       two column arguments.  If the function inputs or outputs a character, 
  59.       there is only one column argument; otherwise there are two.
  60.  
  61.  
  62.  
  63. 2.0 ERROR AND WARNING CHECKING
  64.  
  65. The functions declared in the header <recio.h> make use of the errno macro
  66. defined in section 4.1.3 of ANSI X3.159-1989.  This mechanism was chosen
  67. because (1) the <stdlib.h> conversion functions (strtod(), strtol(), etc.)
  68. make use of this error reporting mechanism and (2) the <recio.h> functions
  69. make use of the <stdlib.h> conversion functions.
  70.  
  71. In this implementation, errno can return the following macro constants:
  72.  
  73.          0 - No error.
  74.     EACCES - permission denied.
  75.     EINVAL - invalid argument (usually null record pointer).
  76.     EMFILE - too many open files.
  77.     ENOENT - no such file or directory.
  78.     ENOMEM - out of memory.
  79.  
  80. Beginning with version 1.1, recio functions set errno when the record 
  81. pointer is invalid and set an internal error number when the record pointer 
  82. is valid.  The recio error number is accessed through the rerror function.
  83.  
  84. The rerror function can return the following macro constants:
  85.  
  86.          0 - No error.
  87.   R_EINVAL - invalid argument (not the record pointer).
  88.  R_EINVDAT - invalid data.
  89.  R_EINVMOD - invalid mode.
  90.  R_EMISDAT - missing data.
  91.   R_ENOMEM - out of memory.
  92.   R_ENOPUT - unable to write data to output.
  93.   R_ERANGE - data out of range.
  94.  
  95. Beginning with version 2.0, recio functions set an internal warning number 
  96. when the record pointer is valid.  The recio library never sets the warning 
  97. number when the record pointer is invalid.  The recio warning number is 
  98. accessed through the rwarning function.
  99.  
  100. The rwarning function can return the following macro constants:
  101.  
  102.          0 - No warning.
  103.  R_WEMPSTR - empty data string.
  104.   R_WNOREG - unable to register exit function with atexit().
  105.   R_WWIDTH - data too wide for columnar output.
  106.  
  107.  
  108. 2.1 Define Callback Error Function
  109.  
  110. First define a callback error function to be used by the recio functions.
  111. You may give the function any name you wish.  In the sample function below,
  112. the name rerrfn is used.  The function takes one argument, a record pointer
  113. (REC *).  It returns nothing (void).  The function must first check for a
  114. valid record pointer using the risvalid function.  Other than that, you can
  115. customize it to do whatever you want.
  116.  
  117. The recio functions use a callback error function in order to give the
  118. most flexibility in handling errors.  This rerrfn function just sends
  119. information to stderr.  You may wish to send information to a printer,
  120. a file, a window, or a dialog box.  You might even want to give users
  121. the ability to examine errors and enter corrections.  If the error is
  122. corrected, you will want to call the rclearerr function before your
  123. callback error function returns.
  124.  
  125. When your callback error function is invoked, check rerror() or errno
  126. to determine the cause of the error.
  127.  
  128. Symbolic errno constants:
  129.  
  130. * EACCESS means that you don't have permission to access this file.  All
  131.   MSDOS files have read permission.
  132.  
  133. * EINVAL indicates an invalid argument to a function, usually a NULL record
  134.   pointer.  This resulted from a programming error.
  135.  
  136. * EMFILE means the program tried to open more files than the maximum allotted
  137.   by ROPEN_MAX or FOPEN_MAX.  If your program is interactive, the user can
  138.   close one or more open record streams.  Or you might decide that ROPEN_MAX
  139.   or FOPEN_MAX needs to be a larger value.
  140.  
  141. * ENOENT says that ropen() could not find the requested file to open.
  142.   Perhaps the name of the file was misspelled, or your program looked in
  143.   wrong directory.  If your program was trying to read a configuration file,
  144.   it could use internal default values when the configuration file does
  145.   not exist.
  146.  
  147. * ENOMEM indicates that the program ran out of heap space.  You may be able
  148.   to correct this if you are able to deallocate memory you no longer need.
  149.   For example, you could reduce the size of buffers when the size only
  150.   affects speed.  Such buffers need to be flushed first.  Buffers used by
  151.   the recio library do not fit this criteria.
  152.  
  153. Symbolic rerror() constants:
  154.  
  155. * R_EINVDAT says the data is invalid.  Invalid data is caused by an 
  156.   unrecognized character in the field.  For example, rgetui() doesn't 
  157.   expect to see a negative sign, so a negative number will be flagged as 
  158.   invalid data.
  159.  
  160. * R_EINVMOD indicates that you opened a file in read mode, then used an output 
  161.   function or opened a file in write or append mode, then used an input
  162.   function.
  163.  
  164. * R_EMISDAT says the data is missing.  Missing data means the field is empty.  
  165.   If you expect a number, you could substitute either zero or some unique 
  166.   number to indicate an empty field.
  167.  
  168. * R_ENOMEM indicates that the program ran out of heap space.  You may be able
  169.   to correct this if you are able to deallocate memory you no longer need.
  170.   For example, you could reduce the size of buffers when the size only
  171.   affects speed.  Such buffers need to be flushed first.  Buffers used by
  172.   the recio library do not fit this criteria.
  173.  
  174. * R_ENOPUT says the program was unable to write the data to output.  This 
  175.   could indicate that the disk is full.
  176.  
  177. * R_ERANGE tells you that the data is outside the range of the function.
  178.   For instance, suppose you used rgeti() to get an integer and the data
  179.   value is 32768.  If a 16-bit integer has an upper limit of 32767, the
  180.   value is too large.  If the data is wrong, you can have the error
  181.   function correct it.  If the data is right, you have to correct the 
  182.   data type in the program.
  183.  
  184. The main purpose of this sample callback error function is to show some of
  185. kinds of things you can do in a callback error function.  Note that when an
  186. error occurs, the column number indicator rcolno() has moved just beyond
  187. the error.  To make it clearer to the user where